home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / watcom / llcomm13 / ll_comm.nfo < prev    next >
Encoding:
Text File  |  1994-08-26  |  17.0 KB  |  455 lines
  1. ------------------------- ---- ---  --  -     -
  2. LL_COMM (R) Lord Logic's Comm Code
  3. Copyright (C) 1994 James P. Ketrenos
  4. ------------------------- ---- ---  --  -     -
  5.  
  6. DATE:   8-27-94
  7.  
  8. All C/C++ code is written in/for Watcom C/C++ v9.5+ using PWB.
  9. All ASM code is written in/for MASM v6.1 using PWB.
  10. Included makefile is for Watcom.
  11.  
  12.  
  13. ------------------------- ---- ---  --  -     -
  14. Files in this package
  15. ------------------------- ---- ---  --  -     -
  16. descript.ion      596   8-27-94  1:12p Norton DOS File Descriptions
  17. lcr.c            9386   8-27-94  1:12p Example Source using LL_COMM   [C]
  18. lcr.exe         58786   8-27-94  1:12p LCR.C Executable
  19. lcr.h            5051   8-27-94  1:12p LCR.H Include file             [C]
  20. lcr.obj          9025   8-27-94  1:12p LCR Compiled Object Code
  21. lcr.nfo           737   8-27-94  1:12p LCR Information
  22. ll_comm.asm     26730   8-27-94  1:12p Main package source            [ASM]
  23. ll_comm.h        5038   8-27-94  1:12p LL_COMM Include file for .C    [C]
  24. ll_comm.nfo     17374   8-27-94  1:12p LL_COMM Documentation
  25. ll_comm.obj      2093   8-27-94  1:12p LL_COMM Assembled Object Code
  26. ll_comm.txt       255   8-27-94  1:12p LL_COMM Brief Description
  27. ll_stat.h         313   8-27-94  1:12p Incremental Status Include     [C]
  28. ll_stat.obj      1660   8-27-94  1:12p LL_STAT Compiled Object Code
  29. makefile         1112   8-27-94  1:12p Watcom C/C++ Makefile for LL_COMM
  30. register.nfo     5199   8-27-94  1:12p Registration Information
  31.               143,355   bytes
  32.  
  33.  
  34. ------------------------- ---- ---  --  -     -
  35. Prologue (yeah, whatever)
  36. ------------------------- ---- ---  --  -     -
  37. The LL_ prefix assigned to the archive name denotes that it is a library
  38. written by me.  All code libraries that I release will use this naming
  39. convention.
  40.  
  41. You'll notice that I code all of my hardware code in assembly to take
  42. advantage, as best as I can, of the hardware.  The usage of those routines
  43. is normally from C as there is no point in coding memory management in
  44. assembly when the Watcom compiler optimizes so well.
  45.  
  46. Code released so far:                                           Code Provided:
  47. LL_KEY.ZIP   ??k    '94 Mult-key, buffered, keyboard IO  ISR    [C/ASM/32bit]
  48. LL_COMM.ZIP  42k    '94 Low-level communication routines ISR    [C/ASM/32bit]
  49. LL_LAND.ZIP 146k    '93 Dot fractal landscape 3D viewer         [C/ASM/16bit]
  50. LL_FRAC.ZIP  33k    '93 Subdivision fractal scape generator     [C/16-bit]
  51.  
  52. To be released:
  53. LL_MCOMM.ZIP ??k    '94 Low-level multi-port routines    ISR    [C/ASM/32bit]
  54. LL_TIME.ZIP  ??k    '94 Timer Reving Code                ISR    [C/ASM/32bit]
  55. LL_VRT.ZIP   ??k    '94 Tripple Buffering VRT ModeX Code ISR    [C/ASM/32bit]
  56. LL_ENGIN.ZIP ??k    '94 Low-level game engine                   [C/ASM/32bit]
  57. LL_VGA.ZIP   ??k    '94 Miscellaneous demo effects              [C/ASM/32bit]
  58.  
  59. ------------------------- ---- ---  --  -     -
  60. Purpose (more drudge)
  61. ------------------------- ---- ---  --  -     -
  62. Hey, I think I'll write a modem->modem game!  Hey, there aren't any decent
  63. communication libraries out there.  Perhaps I should write my own . . .
  64.  
  65. Ok, there were some libraries out there, but none of them were written
  66. for Watcom, and all of the ones that I found crashed when trying to use
  67. my COM3 which is set to IRQ5 instead of IRQ4.  So, I set off in search of
  68. information on coding the 8250 UART, found it, and coded this.
  69.  
  70. This version (1.3) is the second public release of the routines.  Version
  71. 2.0 may or may not come out.  It depends on whether I get feedback on
  72. these routines.
  73.  
  74.  
  75. ------------------------- ---- ---  --  -     -
  76. Where's the ASM????
  77. ------------------------- ---- ---  --  -     -
  78. Its here in this release.  I changed 4 lines in the DOCs, and decided
  79. to release this again with full source.  Lucky you, eh?
  80.  
  81. If you feel these routines deserve some monetary reward, feel free to send
  82. it to the address listed in "Contacting Me".
  83.  
  84. If you know anyone looking to hire a coder, I am in the market.  Resumes
  85. available upon request :)
  86.  
  87.  
  88. ------------------------- ---- ---  --  -     -
  89. Royalties
  90. ------------------------- ---- ---  --  -     -
  91. Please REGISTER.NFO for registration information.
  92.  
  93. These routines represent a lot of my time (well, not a WHOLE lot, but
  94. enough that I deserve a little recognition maybe)  Oh well.
  95.  
  96. ------------------------- ---- ---  --  -     -
  97. Contacting Me
  98. ------------------------- ---- ---  --  -     -
  99. As these routines are my first communications routines, they are
  100. probably bug prone.  I have tested them out as much as I can on my system,
  101. so if you find any bugs, please email them to me describing what the
  102. problem is.
  103.  
  104. Bug reports are not limited to software problems.  Misinformation in my
  105. docs are bugs as well--please report them.  Thank you.
  106.  
  107. If you have any questions about this code, or need help using it, let me
  108. know.
  109.  
  110. The quickest way to reach me is to email me:
  111. ketrenoj@cs.pdx.edu
  112.  
  113. You can snail mail me at: (before June 1995)
  114. James Ketrenos
  115. 885 SW 84th CT
  116. Portland, OR 97225
  117. USA
  118.  
  119.  
  120. ------------------------- ---- ---  --  -     -
  121. Thanks to . . .
  122. ------------------------- ---- ---  --  -     -
  123. Special thanks go out to the people behind Serial.FAQ as it was my sole
  124. source of reliable information.  Without that FAQ, I would not have been
  125. able to write this code.
  126.  
  127. You can obtain the FAQ from the newsgroup news.answers or archie for
  128. serial14 and you should find it there.
  129.  
  130.  
  131.  
  132. ************************* **** ***  **  *     *
  133. Provided Routines
  134. ************************* **** ***  **  *     *
  135. NOTE:       All routines written to take parameters via REGISTER.
  136.             You must include LL_COMM.H or copy its contents into your
  137.             code so that the arguments are parsed into the correct
  138.             registers.
  139.  
  140. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  141. void        ioClearRead(COMM PortID);
  142. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  143. Purpose:    This routine flushes the receiving buffer.
  144.  
  145. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  146.  
  147. Example:    /* If receive buffer has characters, then flush it */
  148.             if (ioReadStatus(PortID))
  149.                 ioClearRead(PortID);
  150.  
  151. See also:   ioClearWrite(), ioReadByte, ioReadPacket(), ioReadStatus()
  152.  
  153.  
  154.  
  155. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  156. void        ioClearWrite(COMM PortID);
  157. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  158. Purpose:    This routine flushes the sending buffer.
  159.  
  160. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  161.  
  162. Example:    /* If send buffer has characters, then flush it */
  163.             if (ioWriteStatus(PortID))
  164.                 ioClearWrite(PortID);
  165.  
  166. See also:   ioClearRead(), ioWriteByte, ioWritePacket(), ioWriteStatus()
  167.  
  168.  
  169.  
  170. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  171. int         ioClosePort(COMM PortID);
  172. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  173. Purpose:    This routine closes communications with the passed port.
  174.             It uninstalls the ISR and frees unecessary buffers.
  175.  
  176. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  177.  
  178. Returns:    0   Success
  179.             !0  Failure (passed PortID did not reference valid port)
  180.  
  181. Example:    /* Closes an open port    */
  182.             if (!ioClosePort(PortID)) {printf("Error!\n");}
  183.  
  184. See also:   ioOpenPort()
  185.  
  186.  
  187.  
  188. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  189. int         ioGetBaud(COMM PortID);
  190. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  191. Purpose:    This routine determines the current baud-rate of
  192.             the port.
  193.  
  194. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  195.  
  196. Returns:    Current baud rate.  No error return (crash if PortID is bad)
  197.  
  198. Example:    /* Show the baud rate */
  199.             printf("Rate: %d\n",ioGetBaud(PortID));
  200.  
  201. See also:   ioSetBaud()
  202.  
  203.  
  204.  
  205. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  206. int         ioGetContol(COMM PortID);
  207. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  208. Purpose:    This routine gets the ports Line Control mode.
  209.  
  210. Pass:       PortID      = An open port ID (returned from ioOpenPort())
  211.  
  212. Returns:    Current Line Control mode.  Modes are combinations of the
  213.             following:
  214.  
  215.             Line Control Modes:
  216.             See ioSetControl()
  217.  
  218. Example:    /* Display BITS Mode */
  219.             switch (ioGetControl(PortID)&(BITS_5|BITS_6|BITS_7|BITS_8))
  220.             {
  221.             case    BITS_5:printf("5 BPW\n"); break;
  222.             case    BITS_6:printf("6 BPW\n"); break;
  223.             case    BITS_7:printf("7 BPW\n"); break;
  224.             case    BITS_8:printf("8 BPW\n"); break;
  225.             default:printf("Tweakin mode... who knows...\n");
  226.             }
  227.  
  228. See also:   ioSetControl, ioGetHandShake, ioGetStatus()
  229.  
  230.  
  231.  
  232. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  233. int         ioGetHandShake(COMM PortID);
  234. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  235. Purpose:    This routine gets the ports handshaking mode.
  236.  
  237. Pass:       PortID      = An open port ID (returned from ioOpenPort())
  238.  
  239. Returns:    Current HandShaking mode.  Modes are combinations of the
  240.             following:
  241.  
  242.             HandShaking Modes:
  243.             See ioSetHandShake()
  244.  
  245. Example:    /* Check to see if in LOOPBACK */
  246.             printf("LOOPBACK %s\n",
  247.                 (ioGetHandShake(PortID)&LOOPBACK) ? "SET" : "NOT SET");
  248.  
  249. See also:   ioSetHandShake, ioGetControl(), ioGetStatus()
  250.  
  251.  
  252.  
  253. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  254. MODE        ioGetMode(COMM PortID);
  255. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  256. NOTE:       Not yet available (scheduled for version 2.0)
  257.  
  258.  
  259.  
  260. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  261. int         ioGetStatus(COMM PortID);
  262. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  263. Purpose:    This routine gets the ports Modem/Line Status mode.
  264.  
  265. Pass:       PortID      = An open port ID (returned from ioOpenPort())
  266.  
  267. Returns:    Current Modem/Line Status mode.  Modes are combinations of the
  268.             following:
  269.  
  270.             Line/Modem Status Modes:
  271.             See LL_COMM.H and consult the Serial.FAQ
  272.  
  273. Example:    Haven't found any use for this one yet . . .
  274.  
  275. See also:   ioGetControl, ioGetHandShake
  276.  
  277.  
  278.  
  279. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  280. COMM        ioOpenPort(int Base, int IRQ);
  281. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  282. Purpose:    This routine, as it is named, opens communications with the
  283.             port.  It installs the ISR and sets various flags for use by
  284.             the other routines.
  285.  
  286. Pass:       Base     = Port base number
  287.             IRQ     = Interrupt ReQuest Number
  288.  
  289. Returns:    Type COMM which is used when calling the other routines
  290.             to reference the opened port on success.
  291.             NUL (0) on failure.
  292.  
  293. Example:    /* Initialize PORT 3f8 IRQ 4 (COM1 typically)   */
  294.             if (!(PortID=ioOpenPort(0x3f8, 4))) {printf("Error!\n");}
  295.  
  296.             The default settings for most systems is as follows:
  297.             ioOpenPort(0x3f8, 4);   // COM1
  298.             ioOpenPort(0x2f8, 3);   // COM2
  299.             ioOpenPort(0x3e8, 4);   // COM3
  300.             ioOpenPort(0x2e8, 3);   // COM4
  301.  
  302. NOTE:       As of this release, there is only single port code so you don't
  303.             really need to keep the value returned.
  304.  
  305. See also:   ioClosePort(), ioSetBaud(), ioSetControl(), ioSetHandShake()
  306.  
  307.  
  308.  
  309. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  310. char        ioReadByte(COMM PortID);
  311. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  312. Purpose:    This routine fetches a byte from the receiving buffer.
  313.  
  314. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  315.  
  316. Returns:    Next character in the buffer
  317.             NUL (0) If buffer is empty
  318.  
  319. Example:    /* While receive buffer has characters, read it */
  320.             while (ioReadStatus(PortID))
  321.                 printf("%c",ioReadByte(PortID));
  322.  
  323. See also:   ioClearRead(), ioWriteByte, ioReadPacket(), ioReadStatus()
  324.  
  325.  
  326.  
  327. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  328. int         ioReadPacket(COMM PortID, PACKET &DataPacket);
  329. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  330. NOTE:       Not yet available (scheduled for version 2.0)
  331.  
  332.  
  333.  
  334. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  335. void        ioSetBaud(COMM PortID, int BaudRate);
  336. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  337. Purpose:    This routine sets the port to a new baud-rate.
  338.  
  339. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  340.             BaudRate= Legal baud rate (1-115200)
  341.  
  342.             Typical rates:
  343.             150, 300, 600, 1200, 2400, 4800, 9600,
  344.             19200, 28800, 38400, 57600, 115200
  345.  
  346. Example:    /* Set the baud rate */
  347.             ioSetBaud(PortID, 57600);
  348.  
  349. See also:   ioGetBaud()
  350.  
  351.  
  352.  
  353. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  354. void        ioSetControl(COMM PortID, int ControlMode);
  355. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  356. Purpose:    This routine sets the ports Line Control mode.
  357.  
  358. Pass:       PortID      = An open port ID (returned from ioOpenPort())
  359.             ControlMode = Bitfield for LC mode.
  360.  
  361.             Line Control Modes:
  362.                 Bits Per Word:
  363.                 BITS_5, BITS_6, BITS_7, BITS_8
  364.  
  365.                 Stop Bits:
  366.                 STOP_1, STOP_2
  367.  
  368.                 Parity:
  369.                 NO_PARITY, ODD_PARITY, EVEN_PARITY,
  370.                 MARK_PARITY, SPACE_PARITY
  371.  
  372.                 Mode:
  373.                 NORMAL, BREAK
  374.  
  375.             You can | (OR) the above together to set different modes.
  376.             BREAK sends a break signal to the port.
  377.  
  378.             Remember, when you are in a 5, 6, or 7 bit mode, only
  379.             the first 5, 6, or 7 least significant bits are sent,
  380.             regardless of what you send to the modem.
  381.  
  382.             For example,  in BITS_6, if you send the '@' character,
  383.             (which is 0x40 in HEX, or 01000000b in BINARY) then only
  384.             the lower 6 bits will be sent making the sent byte have
  385.             the value of 0x00 HEX, or 00000000b BINARY--in other words,
  386.             it sent a NUL.
  387.  
  388. Example:    /* Set the line control to 8-n-1 */
  389.             ioSetControl(PortID, BITS_8 | NO_PARITY | STOP_1);
  390.  
  391. NOTE:       BITS_5 in conjunctions with STOP_2 *might not* work with
  392.             some hardware.
  393.  
  394. See also:   ioGetControl(), ioSetHandShake()
  395.  
  396.  
  397.  
  398. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  399. void        ioSetHandShake(COMM PortID, int ShakeMode);
  400. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  401. Purpose:    This routine sets the ports handshaking mode.
  402.  
  403. Pass:       PortID      = An open port ID (returned from ioOpenPort())
  404.             ShakeMode   = Bitfield for mode.
  405.  
  406.             HandShaking Modes:
  407.             DTR, RTS, LOOPBACK
  408.  
  409.             You can | (OR) the above together to set different modes.
  410.             LOOPBACK mode will not send or receive data through the port
  411.             but will set the port so that whatever is sent out, is routed
  412.             back in instead.  CCAANN  YYOOUU  SSAAYY  EECCHHOO??
  413.  
  414. Example:    /* Set the handshake to normal */
  415.             ioSetHandShake(PortID, DTR | RTS);
  416.  
  417.             /* Set it to loopback */
  418.             ioSetHandShake(PortID, LOOPBACK);
  419.  
  420. See also:   ioGetHandShake(), ioSetControl()
  421.  
  422.  
  423.  
  424. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  425. int         ioSetMode(COMM PortID, MODE PacketMode);
  426. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  427. NOTE:       Not yet available (scheduled for version 2.0)
  428.  
  429.  
  430.  
  431. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  432. int         ioWriteByte(COMM PortID, char Data);
  433. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  434. Purpose:    This routine sends a to the receiving buffer.
  435.  
  436. Pass:       PortID  = An open port ID (returned from ioOpenPort())
  437.             Data    = Character to send to the port
  438.  
  439. Returns:    !0      Successfully sent
  440.             NUL (0) Failure (buffer full)
  441.  
  442. Example:    /* Send a string */
  443.             char    *x;
  444.             for (x="Hello";*x;x++)
  445.                 ioWriteByte(PortID,*x);
  446.  
  447. See also:   ioClearWrite(), ioReadByte, ioWritePacket(), ioWriteStatus()
  448.  
  449.  
  450.  
  451. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  452. int         ioWritePacket(COMM PortID, PACKET &DataPacket);
  453. ------------------- ---- ---  --  -     -   -  --  --- ---- ---------------
  454. NOTE:       Not yet available (scheduled for version 2.0)
  455.